home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / XMSLIB.ARJ / XMSLIB.DOC next >
Text File  |  1991-06-05  |  19KB  |  460 lines
  1.                                     XMSLIB
  2.                          C Interface to XMS Functions
  3.                              XMSLIB version 1.21
  4.                              by James W. Birdsall
  5.                                    06/05/91
  6.  
  7.  
  8. 1. INTRODUCTION
  9. ---------------
  10.  
  11.    XMSLIB provides a high-level interface to XMS control functions for common
  12. operations such as allocating and freeing XMS extended memory blocks (EMBs)
  13. and copying data to and from EMBs. A raw interface has been included to allow
  14. more exotic functions which are not directly supported.
  15.  
  16.  1.1 LEGALESE
  17.  ------------
  18.  
  19.    XMSLIB is not in the public domain. It is copyright 1991 by James W.
  20. Birdsall, all rights reserved. Permission is granted to do the following:
  21.  
  22.           You may freely redistribute this archive, so long as it contains
  23.           all the files listed here {XMSLIB.DOC, XMSLIBS.OBJ, XMSLIBC.OBJ,
  24.           XMSLIBM.OBJ, XMSLIBL.OBJ, XMSTEST.C, XMSLIB.H} intact and
  25.           unmodified.
  26.  
  27.           You may use the object files in programs for your own use. You
  28.           may not distribute programs linked with these object files.
  29.  
  30.    Payment of the $5 shareware registration fee grants the following
  31. additional permissions:
  32.  
  33.           You may obtain the source to XMSLIB, upon request. You may modify
  34.           the source as necessary for use in your programs. However, you may
  35.           not redistribute either the original or modified source.
  36.  
  37.           You may distribute programs linked with either the original
  38.           object files or object files generated from source you have
  39.           modified, without royalty.
  40.  
  41.    The contents of this archive, and all other related files, information,
  42. and services are provided as-is. While every effort has been made to ensure
  43. that the files, information, and services are accurate and correct, the
  44. author cannot be held liable for damages arising out of the use of or
  45. inability to use this product.
  46.  
  47.    Information on contacting the author is provided at the end of this
  48. file.
  49.  
  50.  
  51. 2. USE
  52. ------
  53.  
  54.    XMSLIB is provided as an object file for maximum flexibility. It is
  55. written in Turbo Assembler 2.5, to be compatible with Borland C++ 2.0. Since
  56. Borland C++ has the same calling conventions as Turbo C(++), XMSLIB is
  57. compatible with Turbo C(++).
  58.    According to the documentation for Microsoft C 6.0, the calling
  59. conventions used by MSC are essentially the same. XMSLIB should be compatible
  60. with MSC also, but extensive testing has not been done. What tests could
  61. be performed worked.
  62.  
  63.    XMSLIB is provided for small, medium, compact, and large models. The model
  64. for which the object is intended is indicated by the last letter of the
  65. filename proper, which is the same as the first letter of the model. For
  66. example, XMSLIBL.OBJ is the large-model object. The small object should
  67. probably work with the tiny model, and the large object with the huge model,
  68. but these have not been tested.
  69.  
  70.    To use XMSLIB, choose the appropriate object for the model in which the
  71. rest of your program is compiled, and include that object. Consult your
  72. compiler documentation for how to link in objects. If you are using the
  73. command-line compiler to compile and/or link, simply place the full name
  74. of the XMSLIB object on the command line. If you are linking manually (using
  75. LINK, TLINK, et al.), simply place XMSLIB in with the names of the other
  76. object files being linked.
  77.  
  78.    An example program, XMSTEST.C, has been included. To use it, simply
  79. compile it in whatever memory model you choose and link it with the
  80. appropriate XMSLIB object for that memory model. For example, using the
  81. Borland C++ command-line compiler, the following command would compile
  82. XMSTEST.C in the medium model and link it with XMSLIBM.OBJ:
  83.  
  84.       bcc -mm xmstest.c xmslibm.obj
  85.  
  86. Users of Turbo C(++) can simply substitute "tcc" for "bcc". The following
  87. two commands perform the same function, but demonstrate using TLINK
  88. directly:
  89.  
  90.       bcc -mm -c xmstest.c
  91.       tlink c0m xmstest xmslibm, xmstest, , cm
  92.  
  93. Again, users of Turbo C(++) can simply substitute "tcc" for "bcc". TLINK is
  94. the same for both packages. The files "c0m" and "cm" on the TLINK command
  95. line are the standard medium-model startup object and medium-model library,
  96. respectively.
  97.  
  98.  
  99. 3. GENERAL CONSIDERATIONS
  100. -------------------------
  101.  
  102.    XMSLIB provides a set of functions which are intended to be orthogonal
  103. with the standard C functions malloc()/free(), and the Turbo C function
  104. coreleft().
  105.  
  106.    One point that cannot be stressed sufficiently is that the library
  107. initialization function XMMlibinit() _must_ be called before any other
  108. XMSLIB calls are made. Failure to do so will result in undefined behavior
  109. or crash. One of the important things that XMMlibinit() does is determine
  110. whether there is an XMS driver in the system at all.
  111.  
  112.    All files which call XMSLIB functions should #include the file XMSLIB.H.
  113. This file defines the return and error code symbols shown in section 5,
  114. declares the global variables provided by XMSLIB, and provides prototypes
  115. for the XMSLIB functions.
  116.  
  117.  
  118. 4. LIBRARY FACILITIES
  119. ---------------------
  120.  
  121.  4.1 GLOBAL VARIABLES
  122.  --------------------
  123.  
  124.    XMSLIB provides the following global variables, as shown in the header
  125. file XMSLIB.H:
  126.  
  127.   4.1.1 _XMMerror
  128.   ---------------
  129.  
  130.    _XMMerror is an unsigned char which contains the XMS driver error
  131. code from the last XMS driver call. If there was no error, it will be 0.
  132. A list of error code values and symbolic values is in section 5.
  133.  
  134.   4.1.2 _XMMversion
  135.   -----------------
  136.  
  137.    _XMMversion is an unsigned int which contains the XMS version that the
  138. XMS driver implements. It is in packed BCD format. For example, if the XMS
  139. version is 2.0, the value of _XMMversion will be 0x0200. The high byte of
  140. _XMMerror represents two digits to the left of the decimal point (one digit
  141. per nibble) and the low byte represents two digits to the right of the
  142. decimal point (one digit per nibble).
  143.  
  144.   4.1.3 xmslib_vers_vers, xmslib_vers_date, xmslib_vers_time
  145.   ----------------------------------------------------------
  146.  
  147.    These variables are null-terminated strings containing information about
  148. the name and version of the library, the date of compilation, and the time
  149. of compilation, respectively.
  150.  
  151.  4.2 FUNCTIONS
  152.  -------------
  153.  
  154.    All functions set the variable _XMMerror. If the function completed
  155. successfully, _XMMerror is set to 0. If there was an error, _XMMerror is
  156. set to the appropriate error code. Thus, it is always possible to check
  157. the value of _XMMerror after a function call to check for errors. However,
  158. many functions also indicate success or error by their return value. Those
  159. functions where the return value may be ambiguous are noted, and it is
  160. recommended that _XMMerror be checked instead of the return value.
  161.  
  162.   4.2.1 XMMlibinit()
  163.   ------------------
  164.  
  165.    int XMMlibinit(void)
  166.  
  167.    This function initializes the library. It _must_ be called before any
  168. other XMSLIB calls are made. It returns 0 on success, XMMOOPS if there was
  169. an XMS driver error, or NOXMM if an XMS driver was not detected.
  170.  
  171.   4.2.2 XMMgetversion()
  172.   ---------------------
  173.  
  174.    int XMMgetversion(void)
  175.  
  176.    This function returns the XMS version implemented by the XMS driver. It
  177. is in packed BCD format, the same as in the global variable _XMMversion (see
  178. above). On error, this function returns XMMOOPS and the global variable
  179. _XMMerror will be set to an XMS error code. _XMMerror is set to 0 otherwise.
  180.  
  181.   4.2.3 XMMcoreleft()
  182.   -------------------
  183.  
  184.    unsigned long XMMcoreleft(void)
  185.  
  186.    This function returns the size of the largest EMB, in bytes. Since it is
  187. not possible to allocate a single block larger than the largest EMB, the
  188. size of the largest EMB is generally more useful than the total amount of
  189. free XMS extended memory.
  190.    Note that when all EMBs have been allocated, the driver itself returns an
  191. error (0xA0, XMM_NOFREEX). This behavior is masked by the XMMcoreleft()
  192. function -- if there are no free EMBs, XMMcoreleft() returns 0L instead of
  193. an error.
  194.    The value of _XMMerror should be checked after calling this function.
  195. If an error occurred, _XMMerror will be set to the error code. If the function
  196. completed successfully, _XMMerror will be 0.
  197.  
  198.   4.2.4 XMMallcoreleft()
  199.   ----------------------
  200.  
  201.    unsigned long XMMallcoreleft(void)
  202.  
  203.    This function returns the total amount of free XMS extended memory, in
  204. bytes.
  205.    Note that when all EMBs have been allocated, the driver itself returns an
  206. error (0xA0, XMM_NOFREEX). This behavior is masked by the XMMallcoreleft()
  207. function -- if there are no free EMBs, XMMallcoreleft() returns 0L instead of
  208. an error.
  209.    The value of _XMMerror should be checked after calling this function.
  210. If an error occurred, _XMMerror will be set to the error code. If the function
  211. completed successfully, _XMMerror will be 0.
  212.  
  213.   4.2.5 XMMalloc()
  214.   ----------------
  215.  
  216.    int XMMalloc(unsigned long bytes)
  217.       bytes -- number of bytes to allocate
  218.  
  219.    This function allocates an EMB. It takes the given number of bytes and
  220. rounds upward to the next kilobyte (the XMS driver can allocate EMBs only
  221. in units of kilobytes) and allocates that many kilobytes. It returns the EMB
  222. handle assigned by the XMS driver.
  223.    The value of _XMMerror should be checked after calling this function.
  224. If an error occurred, _XMMerror will be set to the error code. If the
  225. function completed successfully, _XMMerror will be 0.
  226.    Note that EMBs cannot be allocated in units smaller than a kilobyte.
  227. Requesting one byte will allocate 1024 bytes; requesting 1025 bytes will
  228. allocate 2048. However, requesting 0 bytes will allocate a handle but no
  229. bytes. This is explicitly allowed by the XMS specification.
  230.  
  231.   4.2.6 XMMfree()
  232.   ---------------
  233.  
  234.    int XMMfree(int handle)
  235.       handle -- EMB handle to free
  236.  
  237.    This function accepts an EMB handle obtained from the XMMalloc() function
  238. or directly from the XMS driver, and releases it and the EMB allocated to it.
  239. If an error occurred, XMMfree() returns XMMOOPS and _XMMerror will be set to
  240. the error code. If the function completed successfully, XMMfree() returns 0
  241. and _XMMerror will be 0.
  242.  
  243.   4.2.7 _XMMcopy()
  244.   ------------------
  245.  
  246.    int _XMMcopy(unsigned long copylen, int shan, unsigned long soff,
  247.                                                   int dhan, unsigned long doff)
  248.       copylen -- number of bytes to be copied
  249.       shan    -- EMB handle of source
  250.       soff    -- offset in shan of source, or far pointer to source if
  251.                  source in conventional memory
  252.       dhan    -- EMB handle of destination
  253.       doff    -- offset in dhan of destination, or far pointer to destination
  254.                  if destination in conventional memory
  255.  
  256.    This function allows painless copying from conventional memory to an EMB,
  257. from an EMB to conventional memory, from one EMB to another, or even from
  258. one point in conventional memory to another. Areas larger than 64K can be
  259. copied without special treatment. Macros XMMcopyto() and XMMcopyfrom()
  260. (see below) are provided for even easier copying from conventional memory
  261. to an EMB and vice versa, respectively.
  262.    Copylen bytes of data are copied. Copylen must be greater than 1. If shan
  263. is nonzero, it is assumed to be the handle of an EMB, and soff is treated as
  264. a byte offset into the EMB owned by shan. If shan is zero, soff is treated as
  265. a segment:offset far pointer to conventional memory. The pair of shan and
  266. soff indicate where the data is to be copied from (the source). Dhan and doff
  267. work the same way as shan and soff, but indicate where the data is to be
  268. copied to (the destination).
  269.    If an error occurred, XMMOOPS is returned and _XMMerror is set to an error
  270. code. If the function completed successfully, 0 is returned and _XMMerror is
  271. 0.
  272.  
  273.   4.2.8 XMMrawcall()
  274.   ------------------
  275.  
  276.    int XMMrawcall(struct XMMregs *regs)
  277.       regs -- pointer to structure holding values for registers
  278.  
  279.    This function is a raw interface directly to the XMS driver. The XMMregs
  280. structure has fields for the AX, BX, DX, SI, and DS registers, which are the
  281. only ones used by the XMS driver. The values in the structure are placed
  282. in the appropriate registers before the XMS driver is called, and the values
  283. in the registers are copied back into the structure after the XMS driver
  284. call returns.
  285.    Since the XMS specification provides a uniform error indication,
  286. XMMrawcall() is able to tell if the call performed caused an error. If it
  287. did, XMMOOPS is returned and _XMMerror is set to the error code. If it
  288. completed successfully, 0 is returned and _XMMerror is set to 0. The low byte
  289. of the regBX field of the XMMregs structure will also contain the error code
  290. if an error occurred.
  291.    The details of the XMMregs structure are shown in the header file XMSLIB.H.
  292.  
  293.  4.3 MACROS
  294.  ----------
  295.  
  296.    XMSLIB provides a few macros to make calls to _XMMcopy easier.
  297.  
  298.   4.3.1 XMMcopyto()
  299.   -----------------
  300.  
  301.    int XMMcopyto(unsigned long copylen, unsigned char far *source,
  302.                                                   int dhan, unsigned long doff)
  303.       copylen -- number of bytes to be copied
  304.       source  -- far pointer to conventional memory source
  305.       dhan    -- EMB handle of destination
  306.       doff    -- offset in dhan of destination
  307.  
  308.    This macro allows painless copying from conventional memory to an EMB.
  309. Areas larger than 64K can be copied without special treatment.
  310.    Copylen bytes of data are copied. Copylen must be greater than 1. Source
  311. is a far pointer to conventional memory and indicates where the data is to
  312. be copied from. Dhan is the handle of an EMB, and doff is a byte offset into
  313. the EMB owned by dhan. The pair of dhan and doff indicate where the data is
  314. to be copied to.
  315.    If an error occurred, XMMOOPS is returned and _XMMerror is set to an error
  316. code. If the function completed successfully, 0 is returned and _XMMerror is
  317. 0.
  318.  
  319.  
  320.   4.3.2 XMMcopyfrom()
  321.   -------------------
  322.  
  323.    int XMMcopyfrom(unsigned long copylen, int shan, unsigned long soff,
  324.                                                        unsigned char far *dest)
  325.       copylen -- number of bytes to be copied
  326.       shan    -- EMB handle of source
  327.       soff    -- offset in shan of source, or far pointer to source if
  328.                  source in conventional memory
  329.       dest    -- far pointer to conventional memory destination.
  330.  
  331.    This macro allows painless copying to conventional memory from an EMB.
  332. Areas larger than 64K can be copied without special treatment.
  333.    Copylen bytes of data are copied. Copylen must be greater than 1. Shan is
  334. the handle of an EMB, and soff is a byte offset into the EMB owned by shan.
  335. The pair of shan and soff indicate where the data is to be copied from. Dest
  336. is a far pointer to conventional memory and indicates where the data is to
  337. be copied to.
  338.    If an error occurred, XMMOOPS is returned and _XMMerror is set to an error
  339. code. If the function completed successfully, 0 is returned and _XMMerror is
  340. 0.
  341.  
  342.  
  343. 5. ERROR CODES
  344. --------------
  345.  
  346.    This section is a list of the error codes to which the global variable
  347. _XMMerror may be set, and the values and meanings thereof.
  348.  
  349.  5.1 INTERNAL CODES
  350.  ------------------
  351.  
  352.    Internal codes indicate an error in XMSLIB itself.
  353.  
  354.    NAME                 VALUE     MEANING
  355.    ----                 -----     -------
  356.    XMM_TOOSHORT          0x40     Copy length was too short (must be
  357.                                   greater than 1).
  358.  
  359.  5.2 XMS DRIVER CODES
  360.  --------------------
  361.  
  362.    These codes are defined in the XMS specification and are returned by
  363. the XMS driver. They are saved in _XMMerror by XMSLIB without alteration.
  364.  
  365.    NAME                 VALUE     MEANING
  366.    ----                 -----     -------
  367.    XMM_UNIMP             0x80     Function is not implemented
  368.  
  369.    XMM_VDISK             0x81     VDISK device driver was detected
  370.  
  371.    XMM_A20ERROR          0x82     A20 error occurred
  372.  
  373.    XMM_GENERROR          0x83     General driver error occurred
  374.  
  375.    XMM_UNRECERROR        0x84     Unrecoverable driver error occurred
  376.  
  377.    XMM_NOHMA             0x90     HMA (High Memory Area) does not exist
  378.  
  379.    XMM_HMAUSED           0x91     HMA already allocated
  380.  
  381.    XMM_HMATOOBIG         0x92     Request to allocate HMA denied because
  382.                                   amount of HMA requested is less than
  383.                                   minimum parameter given to XMS driver
  384.                                   on its command line
  385.  
  386.    XMM_HMANOALLOC        0x93     HMA is not allocated
  387.  
  388.    XMM_A20STILLEN        0x94     A20 line is still enabled
  389.  
  390.    XMM_NOFREEX           0xA0     All EMBs (Extended Memory Blocks) are
  391.                                   allocated
  392.  
  393.    XMM_NOFREEXHAN        0xA1     No free EMB handles
  394.  
  395.    XMM_BADXHAN           0xA2     EMB handle is invalid
  396.  
  397.    XMM_BADSRCHAN         0xA3     Source EMB handle is invalid
  398.  
  399.    XMM_BADSRCOFF         0xA4     Source offset in EMB is beyond end of EMB
  400.  
  401.    XMM_BADDESTHAN        0xA5     Destination EMB handle is invalid
  402.  
  403.    XMM_BADDESTOFF        0xA6     Destination offset in EMB is beyond end
  404.                                   of EMB
  405.  
  406.    XMM_BADLENGTH         0xA7     Length is invalid
  407.  
  408.    XMM_COPYOVERLAP       0xA8     Overlap in copy request is invalid
  409.  
  410.    XMM_PARITY            0xA9     Parity error was detected
  411.  
  412.    XMM_NOLOCK            0xAA     EMB is not locked
  413.  
  414.    XMM_LOCKED            0xAB     EMB is locked
  415.  
  416.    XMM_TOOMANYLOCKS      0xAC     EMB lock count overflowed
  417.  
  418.    XMM_LOCKFAIL          0xAD     EMB lock failed
  419.  
  420.    XMM_UMBSMALLER        0xB0     UMB (Upper Memory Block) of size requested
  421.                                   is not available; however, a smaller UMB
  422.                                   is available
  423.  
  424.    XMM_NOFREEUMB         0xB1     All UMBs are allocated
  425.  
  426.    XMM_BADUMBHAN         0xB2     UMB handle (same as segment address of
  427.                                   start of UMB) is invalid
  428.  
  429.  
  430. 6. THE END
  431. ----------
  432.  
  433.    Technical support via email is available from the following addresses:
  434.  
  435.    INTERNET:
  436.       First choice (the following are alternate addresses for the same place):
  437.          picarefy!support@amc.com
  438.          amc-gw!picarefy!support@coco.ms.washington.edu
  439.          halcyon!picarefy!support@sumax.seattleu.edu
  440.          eskimo!picarefy!support@quick.com
  441.          uunet!uw-coco!amc-gw!picarefy!support
  442.  
  443.       Second choice:
  444.          jwbirdsa@amc.com
  445.  
  446.    COMPUSERVE:
  447.       71261,1731
  448.  
  449.    AMERICA ON-LINE:
  450.       GreenTiger
  451.  
  452.    GENIE:
  453.       J.BIRDSALL2
  454.  
  455.    Registrations should be sent to:
  456.  
  457.       James W. Birdsall
  458.       11112 NE 124 LN #D204
  459.       Kirkland, WA 98034
  460.